Errata for Squirrel
===================

This file covers details which were erroneously omitted or incorrect in the
manual at time of print.

4.21 Default field entries
--------------------------

Facilities using system variables have been added since the manual was
printed. They enable fields and queries (see 6.26 below) to be
parameterised.

Default field entries can be defined as a system variable, which may have
been set according to the environment of the user. For example, in a
multi-user/network environment, a table could have a field which requires
the user's initials. Users can share the same table, but have different
default entries, such as:

*Set My$Initials DNF

This could be set automatically as part of the !ArmBoot file when logging on
to the file server, or as part of the !Boot file of the computer.

To set the default entry to be a system variable, precede the default entry
by an '@' symbol, e.g. @My$Initials. In create table mode, use the default
entry option in the sub-menu of the Validation menu found in the Field
details dialogue box.

If you require a default entry to actually start with an '@' symbol, the
system variable evaluation can be disabled by preceding with another '@',
i.e. '@@'.

The maximum length of the evaluated variable must not exceed 255 characters,
otherwise the field will be left blank. It is also left blank if the
variable is not set.

5.9 The browse tool window
--------------------------

The manual does not indicate that this window can be made to appear or not
appear by default when loading a table. This can be configured from
create/edit table mode by turning the field type tool window on or off
according to the state prefered. When the table is re-saved, the state of
the tool window will be remembered and will dictate the state of the browse
tool window.

5.10 List mode
--------------

The manual is incorrect about the default number of rows being 10 (page
5.10): it has been changed to be calculated automatically to fit the screen
size, indicated by the text 'Auto' in the 'Number of rows' writable icon in
the List mode dialogue box. If required, a number can be specified by
deleting the 'Auto' text from this icon.

5.13 Tool window browse control buttons in Data mode
----------------------------------------------------

The browse buttons index by the field containing the caret - like the PAGE
UP and PAGE DOWN keys. If the window does not contain the caret, then it
will index by the first field, or the last field that the caret was in if it
is not in another data mode or query mode window.

5.18 Data entry comparing against validation list
-------------------------------------------------

The manual does not indicate that abbreviated entries are accepted and the
field contents are replaced with the nearest match in the validation list,
for example:

Validation list is:
 Blue
 Green
 Orange
 Grey

If the user enters
 gr
then this will be replaced by
 Green

If 'Green' and 'Grey' are swapped in the validation list, then 'gr' will be
replaced by 'Grey'.

Note a problem in the following case:
Validation list is :
 Room
 Chairman
 Chair
 Table

If the user enters
 Chair
then this will be replaced by
 Chairman

The solution to this is to ensure that the validation list is in
alphabetical order, or if this is not desired, ensure that the shorter word
is in the list before the longer word, hence the following list would work
OK:
 Room
 Chair
 Chairman
 Table

6.4 List format in query data mode
----------------------------------

The manual does not indicate that list mode is available from query data
mode, i.e. when browsing through records in a query, these can be viewed in
list format rather than just card format. There is an extra menu option in
the 'Query data' menu for achieving this.

A query can be defined to automatically display the query data in list mode
instead of card mode by pressing F8 instead of F1 to execute the query.
Auto-run queries which are configured to Execute will use the mode
displayed, when last executed, before saving the query file:

1. Create a view containing the fields you want displayed in the list mode.

2. Define the query. If the selection criteria uses fields not in the view,
then they should be specified in the filter diagram.

3. Place the caret in a field in the Query window and press F8, the List
query data will be displayed.

4. Press F4, the Query window will be displayed.

5. Choose the Batch operations Auto run menu option and select the Execute
query action, then click OK.

6. Save the query file. When reloaded and executed, the query data will be
displayed in list mode. If you need to convert it back to card mode, execute
the query by pressing F1, press F4 to bring back the Query window and save
again.

6.8 Use of the Escape key for stopping query execution
------------------------------------------------------

Screenshots of the query menu and the description of the 'Stop query'
menu item in the manual do not indicate that pressing 'Escape' has the same
effect as choosing this option.

6.12 Batch update fields
------------------------

The normal SELECT-dragging operation on a boolean field causes it to change
state, e.g. from ? to tick. This can be avoided by pressing ADJUST instead
of SELECT to drag the field.

As expressions can be used in queries and calculated fields, they can also
be used in batch update fields (see pg 8.6, 8.7 for more details). For
example, if a user has a number of tables which he/she wants to increase the
price field for them, a batch update field could be defined like this:

Field New value
----- ---------
price price * (1 + 20 / 100)

System variables can also be used, for example:

Field New value
----- ---------
price price * (1 + @My$Percent_Increase / 100)

where the system variable is set like this:

*Set My$Percent_Increase 20

Note, as in calculated fields (explained in 8.7 below), the system variable
must be followed by a space (' ') before it is followed by the rest of the
expression.

If you are updating string fields or date fields, then the 'New value' must
be preceded by an '=' to imply that it must be set from an expression (which
may contain system variables or fields), rather than the explicit string.

For example, to update a field called full_name with the contents of
first_name and surname and a date field with today's date:

Field     New Value
-----     ---------
full_name =first_name + ' ' + surname
date      =DATE TODAY

Note that the system variable definitions must include the single quotes, as
in the query selection criteria explained in 6.26 below.

6.21 Sorting string fields in queries
-------------------------------------

When dragging a string field into the sort order window, the type of sort
performed defaults to DICTIONARY instead of ASCII as indicated in the manual.

6.26 Query selection criteria
-----------------------------

Items in the boxes of the filter window can include system variables. For
example, if a teacher wants to execute a query on a 'Students' table to find
all the pupils in his/her class, then this can be achieved in a filter box
like this:

class = @My$Class

where the system variable is set in the following way:

*Set My$Class '3B'

Note that the quotes are omitted from the filter box for string fields and
are inserted in the variable. The reason for this is so that '@' characters
are not expanded if contained within quotes in the filter box, and hence can
still be searched for. This might be a problem if you want to use a variable
which is already defined for use as a default field entry, e.g. My$Initials,
which does not have quotes, hence you would need to set a second variable
for use in the query like this:

*SetMacro My$Initials_Q '<My$Initials>'

This is then effectively the same variable but contained within quotes and
would be inserted in a filter box like this:

initials = @My$Initials_Q

The system variables can also be used as part of expressions in the filter
boxes, e.g.

age < @My$Age + 3

You may even use a system variable to specify the complete query, e.g.:

@My$Query$Staff

in the filter box and could be specified by:

*Set My$Query$Staff "(department = 'Sales' OR department = 'Development')
AND area = 'Southsea'"

The maximum length of the evaluated variable must not exceed 1023
characters.

Note: system variables cannot be used in simple queries.

6.30 Combining Simple queries and Filter queries
------------------------------------------------

In querymode, when 'Show filter' is performed, any data in the fields gets
moved to boxes in the filter diagram. A complex filter diagram can be
created (e.g. relational join) in addtion to further selection criteria which
may be specified in the simple query. The resultant query is the filter
diagram ANDed with the simple query.

7.10 Graphing
-------------

1. An option to choose 'Portrait' type graph has been added to the menu in
the Graph Plotting window.

2. A menu has been added to the Graph window to allow the graph to be saved
as a drawfile or printed.

3. The manual indicates that multiple fields can be plotted but does not
accurately explain how to achieve this: if another field is dropped in the
'Plot' box, it will replace the field that is already in there. To prevent
this from happening, a comma must be manually typed in the plot box at the
end of the existing field name before dropping in the next field.

8.7 Calculated fields
---------------------

System variables can be used as part of expressions in calculated
fields, e.g.

net_price * (1 + @My$VAT )

Note that whatever follows the system variable name (in this example, a ')')
has to be separated from the variable name by a space (' ').

9.15 Editing report layouts
---------------------------

When editing report layouts, they behave differently according to the type
of default report chosen:-

Label -

A blue label grid is displayed as a guide line to show what will fit in a
label. When the number across is specified greater than 1, the column width
is fixed to the label width, rather than the furthest right hand edge of any
item in the layout. Note also, that 'Offset from margins' is switched off
because it uses the margins defined in the label definition.

Draft -

The grid locking is forced to ON and the sizes are set to X = 18 (10
characters per inch) and Y = 30 (6 lines per inch). Items added to the
report layout default to draft font (Corpus.Medium 12 point).

Dropping items in the layout

The manual indicates that when an item is dropped in, the mouse pointer
represents the position of the top left hand corner of the item. This only
applies to files dropped in; for fields and field headings, they will be
positioned as indicated by the drag box. Beware that the field will not be
dropped in unless the pointer is in the work area of the report layout
window.

X.XX Loading tables from Waiter menu commands
---------------------------------------------

The manual does not indicate how to achieve loading of tables through the
operating command line interpreter. If you want to load a table using a
Waiter menu option, or a line in an obey file, there are two utilities which
allow this to be achieved:

1) Multi-user Network tables are loaded using the following command:

SqlFiler:NetLoad <tablename>

e.g.

SqlFiler:NetLoad <SqlServer$@DSLTables>.Dave.Countries

2) Local tables are loaded using either of the following commands:

Filer_Run <tablename> (Note: RISC OS 3 ONLY)

or

Squirrel:Start <tablename>

Note that the tablenames are case sensitive

12.XX Autoaction SqlImport
--------------------------

SqlImport can run an import process automatically if the import filename is
given as a parameter when !SqlImport is run. A command (or file) can be
specified to run on completion of the import process by specifying it as the
second parameter, for example, from an obeyfile (or Waiter option):

Run adfs::4.$.Squirrel.!SqlImport adfs::4.$.Importfile adfs::4.$.Obeyfile
